Skip to main content

API Authentication

Cyberhaven uses token-based authentication to secure API endpoints. The process requires creating an API key and using it to generate temporary bearer tokens.

Prerequisites​

Before authenticating, you must create a role with API permissions. See Users & API Keys for role creation.

Authentication Process​

1. Generate API Key​

  1. Navigate to Settings > Users & API keys > API Keys tab
  2. Click New API Key
  3. Enter a descriptive name
  4. Select an appropriate role
  5. Set validity period (maximum 1 year)
  6. Click Save and copy the key immediately

2. Generate Access Token​

Use the API key to generate a temporary bearer token:

Endpoint: POST /v2/auth/token/access

Request Body:

{
  "api_key": "your-api-key-here"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

3. Use Bearer Token​

Include the access token in the Authorization header for all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Using the API Explorer​

Test APIs directly in the Console:

  1. Navigate to Administration > API specification
  2. Click on any endpoint
  3. Use the Try button to test requests
  4. The explorer automatically handles token generation

Token Management​

Token Validity​

  • Access tokens: Valid for 15 minutes
  • API keys: Valid for up to 1 year (configurable)

Token Renewal​

Access tokens must be renewed before expiration. Implement automatic renewal in your applications.

Security Best Practices​

  • Store API keys securely
  • Use HTTPS for all requests
  • Implement token refresh logic
  • Monitor API key usage
  • Rotate keys regularly

Rate Limiting​

  • 60 requests per minute per API key
  • 5 concurrent requests per endpoint
  • 429 status code when limits exceeded

Error Responses​

Common authentication errors:

  • 401 Unauthorized: Invalid or expired token
  • 403 Forbidden: Insufficient permissions
  • 429 Too Many Requests: Rate limit exceeded

Support​

For integration assistance: